개발자 퀵스타트
개발자 퀵스타트 (Developer quickstart)
OpenAI API로 첫 호출을 돌려보는 방법부터 텍스트 생성, 이미지 분석, 에이전트 만들기까지, 가장 먼저 시작하는 길을 안내해 드릴게요.
출처: 문서
본문
OpenAI API는 텍스트 생성, 자연어 처리, 컴퓨터 비전 등 최신 AI 모델에 일관된 인터페이스를 제공해요. API 키를 만들고 첫 API 호출을 실행하는 것부터 시작해요. 텍스트 생성과 이미지 분석, 에이전트 구축 방법까지 살펴볼 수 있어요.
API 키 만들고 내보내기
시작하기 전에 대시보드에서 API 키를 만들어요. 그 키로 안전하게 API에 접근할 수 있어요. 키는 .zshrc 파일 같은 안전한 위치에 저장하고, 터미널에서 환경 변수로 내보내요.
macOS / Linux:
export OPENAI_API_KEY="your_api_key_here"
Windows (PowerShell):
setx OPENAI_API_KEY "your_api_key_here"
각 OpenAI SDK는 시스템 환경에서 API 키를 자동으로 읽어요.
SDK 설치하고 첫 API 호출 실행
JavaScript — Node.js, Deno, Bun 같은 서버 사이드 환경에서는 공식 TypeScript·JavaScript용 OpenAI SDK를 써요.
npm install openai
example.mjs 파일을 만들고 예제 코드를 넣어요:
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra",
input: "Write a one-sentence bedtime story about a unicorn.",
});
console.log(response.output_text);
node example.mjs로 실행하면(Deno·Bun도 동일) 잠시 후 API 응답이 출력돼요.
Python — 공식 Python용 OpenAI SDK를 pip로 설치:
pip install openai
example.py:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input="Write a one-sentence bedtime story about a unicorn.",
)
print(response.output_text)
python example.py로 실행하면 결과가 나와요.
.NET / Java / Go / Ruby — 각 언어의 공식 SDK도 같은 패턴이에요: 키를 환경 변수에서 읽고, client.responses.create(...) 형태로 Requests API를 호출합니다. 자세한 예시는 SDK 및 CLI 문서를 참고하세요.
- .NET:
dotnet add package OpenAI - Java(Maven):
com.openai:openai-java:4.69.3 - Go:
github.com/openai/openai-go/v3 - Ruby:
gem "openai"
실전 앱을 만들 때는 Responses starter app을, 프롬프팅과 메시지 역할, 대화형 앱 구성은 텍스트 생성 가이드를 참고하세요.
크레딧을 추가해 계속 만들기
무료 테스트 요청을 성공적으로 실행했으니 이제 본격적인 앱을 만들어 볼 차례예요. 더 높은 한도로 실제 애플리케이션을 빌드하고 모델로 텍스트·오디오·이미지·비디오를 생성해 보세요. 더 빨리 출시하는 데 도움이 되는 도구와 문서:
- Chat Playground — 대화형 프롬프트를 만들고 테스트해 앱에 임베드
- Build agents — Agents SDK로 에이전트 워크플로를 만들고 실행하고 관찰
이미지와 파일 분석
이미지 URL, 업로드 파일, PDF 문서를 모델에 직접 보내 텍스트 추출, 콘텐츠 분류, 시각적 요소 탐지를 할 수 있어요.
Image URL:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "What teams are playing in this image?",
},
{
"type": "input_image",
"image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
},
],
}
],
)
print(response.output_text)
curl로도:
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is in this image?"},
{"type": "input_image", "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"}
]
}
]
}'
File URL — PDF 같은 파일 URL을 input_file로 넣어요:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Analyze the letter and provide a summary of the key points.",
},
{
"type": "input_file",
"file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
},
],
},
],
)
print(response.output_text)
Upload file — 로컬 파일을 먼저 업로드하고 file_id를 넘겨요:
from openai import OpenAI
client = OpenAI()
file = client.files.create(file=open("draconomicon.pdf", "rb"), purpose="user_data")
response = client.responses.create(
model="gpt-6-astra",
input=[
{
"role": "user",
"content": [
{
"type": "input_file",
"file_id": file.id,
},
{
"type": "input_text",
"text": "What is the first dragon in the book?",
},
],
}
],
)
print(response.output_text)
curl로:
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer ***" \
-F purpose="user_data" \
-F file="@draconomicon.pdf"
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{"type": "input_file", "file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"},
{"type": "input_text", "text": "What is the first dragon in the book?"}
]
}
]
}'
이미지 입력은 이미지 입력 가이드, 파일 입력은 파일 입력 가이드를 참고하세요.
도구로 모델 확장하기
도구를 붙여 모델에 외부 데이터와 함수를 줄 수 있어요. 웹 검색·파일 검색 같은 내장 도구를 쓰거나, API 호출·코드 실행·타사 시스템 통합을 위한 자신만의 도구를 정의할 수 있어요.
Web search — 응답에 웹 검색을 사용:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
tools=[{"type": "web_search"}],
input="What was a positive news story from today?",
)
print(response.output_text)
File search — vector store로 내 파일을 검색:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input="What is deep research by OpenAI?",
tools=[{"type": "file_search", "vector_store_ids": ["<vector_store_id>"]}],
)
print(response)
Code Interpreter — 수학 문제 같은 걸 코드로 풀게 하려면:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
input="I need to solve the equation 3x + 11 = 14. Can you help me?",
)
print(response.output_text)
Function calling — 자신의 함수를 호출하게 하려면 function 타입 도구로 스키마를 정의해요:
from openai import OpenAI
client = OpenAI()
tools = [
{
"type": "function",
"name": "get_weather",
"description": "Get current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia",
}
},
"required": ["location"],
"additionalProperties": False,
},
"strict": True,
},
]
response = client.responses.create(
model="gpt-6-astra",
input=[
{"role": "user", "content": "What is the weather like in Paris today?"},
],
tools=tools,
)
print(response.output[0].to_json())
Remote MCP — 원격 MCP 서버를 도구로 연결:
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
tools=[
{
"type": "mcp",
"server_label": "dmcp",
"server_description": "A Dungeons and Dragons MCP server to assist with dice rolling.",
"server_url": "https://dmcp-server.deno.dev/mcp",
"require_approval": "never",
},
],
input="Roll 2d4+1",
)
print(resp.output_text)
내장 도구에 대한 더 자세한 내용은 도구 가이드를 참고하세요.
더 알아보기 (Learn more)
첫 단계를 넘어서려면 SDK 및 CLI, 모델 인덱스, 텍스트 생성 가이드를 차례로 만나보세요.