Use JSON Mode to connect the model with application code

Beyond chat, Stepfun models can drive application logic—for example, sentiment analysis of reviews or content scoring. You can design prompts that return structured outputs. JSON Mode helps you get machine-parseable JSON for easier integration.

How to use it

To use JSON Mode, do three things:

In the system prompt, describe the expected JSON structure (JSON Schema-style descriptions are recommended).
Set response_format to { "type": "json_object" } so the model returns parsable JSON.
Parse the result and validate it. Once it matches expectations, pass it into your business logic.

Sample code

Here’s an example sentiment analyzer that returns JSON:

from openai import OpenAI

# Initialize Stepfun client
STEPFUN_KEY = ""

client = OpenAI(
    base_url="https://api.stepfun.ai/v1",
    api_key=STEPFUN_KEY
)

# Define the system prompt
system_prompt = """
You are a review analyst. Based on the user's input, identify sentiment and output the analysis result.
## Rules
1. If the review contains negative words, set emotion to negative.
2. If the review contains positive words, set emotion to positive.
3. If neither, set emotion to neutral.
## Positive words
- good
- great
- excellent
## Negative words
- bad
- terrible
- awful
## Examples
### Example 1
#### Input
"This product is really good. I love it."
#### Output
{
    "emotion": "positive",
    "score": 0.9,
    "reason": "The review contains positive words"
}
### Example 2
#### Input
"This product is trash. I hate it."
#### Output
{
    "emotion": "negative",
    "score": 0.9,
    "reason": "The review contains negative words"
}
## Input
User review text
## Output
Return JSON with the following structure:

class Response:
    emotion: str # Sentiment of the review: positive, negative, or neutral
    score: float # Sentiment score between 0 and 1
    reason: str # Explanation for the sentiment

"""

response = client.chat.completions.create(
  model="step-3.7-flash",
  messages=[
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": "Is this product any good?"}
  ],
  response_format={ "type": "json_object" },
)

print(response)

Use JSON Schema to guide structure

Sometimes the model may drift from the expected shape. Adding a JSON Schema can clarify your intent. You can define required fields, meanings, and ranges. For example, the Schema below expects an object with url and notes, both required:

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"title": "User input parsing",
	"type": "object",
	"properties": {
		"url": {
			"type": "string",
			"description": "The URL provided by the user"
		},
		"notes": {
			"type": "string",
			"description": "The user's comments about the URL"
		}
	},
	"required": ["url", "notes"]
}

Include the Schema in your prompt and enable JSON Mode so the model returns content in the exact structure you want:

You are a text-processing engineer. Extract the URL and the user's comments from the input and return them as JSON.

## Constraint

- Return data that conforms to the JSON Schema below.

{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "User input parsing",
"type": "object",
"properties": {
"url": {
"type": "string",
"description":"The URL provided by the user"
},
"notes": {
"type": "string",
"description":"The user's comments about the URL"
}
},
"required": [
"url",
"notes"
]
}

Notes

When using JSON Mode, check whether finish_reason is stop. If it is length, the model hit max_tokens and the JSON may be incomplete or unparsable.
Provide input/output examples in the prompt to help the model understand your scenario and produce outputs that match expectations.

​How to use it

​Sample code

​Use JSON Schema to guide structure

​Notes

How to use it

Sample code

Use JSON Schema to guide structure

Notes